Crate jemalloc_ctl

jemalloc control and introspection.

jemalloc offers a powerful introspection and control interface through the mallctl function. It can be used to tune the allocator, take heap dumps, and retrieve statistics. This crate provides a typed API over that interface.

While mallctl takes a string to specify an operation (e.g. stats.allocated or stats.arenas.15.muzzy_decay_ms), the overhead of repeatedly parsing those strings is not ideal. Fortunately, jemalloc offers the ability to translate the string ahead of time into a "Management Information Base" (MIB) to speed up future lookups.

This crate provides both a function and a type for each mallctl operation. While the function is more convenient, the type will be more efficient if the operation will be repeatedly performed. Its constructor performs the MIB lookup, so the struct should be saved if the same operation is going to be repeatedly performed.

Examples

Repeatedly printing allocation statistics:

extern crate jemallocator;
extern crate jemalloc_ctl;

use std::thread;
use std::time::Duration;

#[global_allocator]
static ALLOC: jemallocator::Jemalloc = jemallocator::Jemalloc;

fn main() {
    loop {
        // many statistics are cached and only updated when the epoch is advanced.
        jemalloc_ctl::epoch().unwrap();

        let allocated = jemalloc_ctl::stats::allocated().unwrap();
        let resident = jemalloc_ctl::stats::resident().unwrap();
        println!("{} bytes allocated/{} bytes resident", allocated, resident);
        thread::sleep(Duration::from_secs(10));
    }
}

Doing the same with the MIB-based API:

extern crate jemallocator;
extern crate jemalloc_ctl;

use std::thread;
use std::time::Duration;

#[global_allocator]
static ALLOC: jemallocator::Jemalloc = jemallocator::Jemalloc;

fn main() {
    let epoch = jemalloc_ctl::Epoch::new().unwrap();
    let allocated = jemalloc_ctl::stats::Allocated::new().unwrap();
    let resident = jemalloc_ctl::stats::Resident::new().unwrap();
    loop {
        // many statistics are cached and only updated when the epoch is advanced.
        epoch.advance().unwrap();

        let allocated = allocated.get().unwrap();
        let resident = resident.get().unwrap();
        println!("{} bytes allocated/{} bytes resident", allocated, resident);
        thread::sleep(Duration::from_secs(10));
    }
}

Modules

arenas	Arena operations.
config	Information about the jemalloc compile-time configuration
opt	Information about the run-time jemalloc configuration.
stats	Global allocator statistics.
stats_print	Bulk statistics output.
thread	Thread specific operations.

Structs

BackgroundThread	A type providing access to the state of internal background worker threads.
Epoch	A type providing access to the jemalloc epoch.
MaxBackgroundThreads	A type providing access to the maximum number of background threads that will be created.
Version	A type providing access to the jemalloc version string.

Functions

background_thread	Returns the state of internal background worker threads.
epoch	Advances the jemalloc epoch, returning it.
max_background_threads	Returns the maximum number of background threads that will be created.
set_background_thread	Enables or disables internal background worker threads.
set_max_background_threads	Sets the maximum number of background threads that will be created.
version	Returns the jemalloc version string.